home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 February: Tool Chest / Dev.CD Feb 94.toast / Tool Chest / Development Platforms / AppsToGo / AppsToGo.src / DTS.Lib / DTS.Lib.headers / TreeObj.h < prev    next >
Encoding:
C/C++ Source or Header  |  1993-06-18  |  14.3 KB  |  433 lines  |  [TEXT/MPS ]
  1. #ifndef __TREEOBJ__
  2. #define __TREEOBJ__
  3.  
  4. #ifndef __TYPES__
  5. #include <Types.h>
  6. #endif
  7.  
  8. #ifndef __ERRORS__
  9. #include <Errors.h>
  10. #endif
  11.  
  12. #ifndef __EVENTS__
  13. #include <Events.h>
  14. #endif
  15.  
  16. #ifndef __MEMORY__
  17. #include <Memory.h>
  18. #endif
  19.  
  20. #define NO_EDIT 0                        /* System edit type. */
  21.  
  22.  
  23. /********/
  24.  
  25.  
  26. #define EMPTYOBJ    0
  27. #define ROOTOBJ     1
  28. #define UNDOOBJ     2
  29. #define UNDOTASKOBJ 3
  30. #define UNDOPARTOBJ 4
  31. #define WFMTOBJ     5
  32. #define CTLOBJ      6
  33.  
  34. #define kCStr       0
  35. #define kPStr       1
  36. #define kSDataBlock 2
  37. #define kLDataBlock 3
  38.  
  39. struct FileRec;
  40. typedef struct FileRec *FileRecPtr, **FileRecHndl;
  41.  
  42. struct TreeObj;
  43. typedef struct TreeObj *TreeObjPtr, **TreeObjHndl;
  44. typedef long    (*TreeObjProcPtr)(TreeObjHndl hndl, short message, long data);
  45.  
  46. typedef struct TreeObj {
  47.     short        type;
  48.     short        numChildren;
  49.     long        dataSize;
  50.     long        treeID;
  51.     TreeObjHndl    parent;
  52. } TreeObj;
  53.  
  54. long    TUndoObj(TreeObjHndl hndl, short message, long data);
  55. typedef struct {
  56.     TreeObjHndl    root;
  57.     FileRecHndl    frHndl;
  58.     Boolean        disabled;
  59.     short        lastEditType;
  60.     short        undoDepth;
  61.     short        maxNumUndos;
  62.     short        numSaveUndos;
  63. } UndoObj;
  64.  
  65. long    TUndoTaskObj(TreeObjHndl hndl, short message, long data);
  66. typedef struct {
  67.     short    editType;
  68.     Point    undoOrigin;
  69.     Point    redoOrigin;
  70. } UndoTaskObj;
  71.  
  72. long    TUndoPartObj(TreeObjHndl hndl, short message, long data);
  73. typedef struct {
  74.     short        actionType;
  75.     TreeObjHndl    shndl;
  76.     short        scnum;
  77.     TreeObjHndl    dhndl;
  78.     short        dcnum;
  79.     Boolean        deepCopy;
  80. } UndoPartObj;
  81.  
  82. struct VHFormatData {
  83.     Handle    text;
  84.     char    *header;
  85.     char    *data;
  86. };
  87. typedef struct VHFormatData VHFormatData;
  88. typedef VHFormatData *VHFormatDataPtr;
  89.  
  90. #define mDerefUndo(hndl)     ((UndoObj*)((*hndl) + 1))
  91. #define mDerefUndoTask(hndl) ((UndoTaskObj*)((*hndl) + 1))
  92. #define mDerefUndoPart(hndl) ((UndoPartObj*)((*hndl) + 1))
  93.  
  94.  
  95. /********/
  96.  
  97.  
  98. #define INITMESSAGE        0        /* Additional object initialization. */
  99. #define     CREATEINIT         0    /* Object being initially created. */
  100. #define     WINDOWINIT         1    /* Document/object being assigned to a window. */
  101. #define     NOWINDOWINIT       2    /* Document/object being freed from a window. */
  102.  
  103. #define FREEMESSAGE        1        /* Additional object disposal. */
  104.  
  105. #define COPYMESSAGE        2        /* Additional object cloning. */
  106.  
  107. #define UNDOMESSAGE        3        /* Additional object undo. */
  108. #define     UNDOFROMDOC        0    /* Object leaving document. */
  109. #define     UNDOTODOC          1    /* Object returning to document. */
  110.  
  111. #define CONVERTMESSAGE     4        /* Hndl2ID or ID2Hndl conversions. */
  112. #define     CONVERTTOID        0    /* Convert handle references to ID references. */
  113. #define     CONVERTTOHNDL    1        /* Convert ID references to handle references. */
  114.  
  115. #define FREADMESSAGE       5        /* Read object data from file. */
  116. #define FWRITEMESSAGE      6        /* Write object data to file. */
  117.  
  118. #define HREADMESSAGE       7        /* Read object data from handle. */
  119. #define HWRITEMESSAGE      8        /* Write object data to handle. */
  120.  
  121. #define HITTESTMESSAGE     9        /* Test if object was hit. */
  122. #define     HITTESTOBJ         0    /* Test body of object for hit. */
  123. #define     HITTESTGRABBER     1    /* Test sizing parts for hit. */
  124. #define     CANBETARGET        2    /* Return true if object can become target. */
  125. #define     CANTAKEKEYS        3    /* Return true if target can take keys. */
  126.  
  127. #define GETRGNMESSAGE      10        /* Return object defining rect. */
  128. #define GETOBJRECTMESSAGE  11        /* Return object defining rect. */
  129. #define SETOBJRECTMESSAGE  12        /* Set object bounding box. */
  130. #define SECTOBJRECTMESSAGE 13        /* Check if rect intersects object bounding box. */
  131.  
  132. #define GETBBOXMESSAGE     14        /* Return rect that contains entire graphic image. */
  133.  
  134. #define DRAWMESSAGE        15        /* Draw some form of the object. */
  135. #define     DRAWOBJ            0    /* Draw the object. */
  136. #define     ERASEOBJ           1    /* Draw the object. */
  137. #define     DRAWSELECT         2    /* Draw the selection portion of the object. */
  138. #define     DRAWGHOST          3    /* Draw an xor-ghost (for dragging) of the image. */
  139. #define     DRAWMASK           4    /* Draw a mask of the image (for offscreen layer masking.) */
  140.  
  141. #define PRINTMESSAGE       16
  142.  
  143. #define VHMESSAGE          17        /* Format View Hierarchy information for the object. */
  144.  
  145. #define COMPAREMESSAGE     18        /* Compare data of two objects of same type. */
  146.  
  147.  
  148.  
  149. #define DOUNDO 0
  150. #define DOREDO 1
  151.  
  152.  
  153.  
  154. TreeObjHndl    NewRootObj(short ctype, long size);
  155.     /* Creates an object with no parent.  This object will be the root object
  156.     ** for a tree.  Returns nil upon failure. */
  157.  
  158.  
  159.  
  160. TreeObjHndl    NewChild(short editType, TreeObjHndl parentHndl, short childNum, short ctype, long size);
  161.     /* Creates a child of the specified type and adds it to the parent at the
  162.     ** specified location.  Returns nil upon failure. */
  163.  
  164.  
  165.  
  166. void        DisposeChild(short editType, TreeObjHndl parentHndl, short childNum);
  167.     /* Disposes of the specified child and all offspring of that child. */
  168.  
  169.  
  170.  
  171. TreeObjHndl    CopyChild(short editType, TreeObjHndl shndl, short scnum, TreeObjHndl dhndl, short dcnum, Boolean deepCopy);
  172.     /* Copies the specified child (and all offspring of that child if deepCopy is true). */
  173.  
  174.  
  175.  
  176. OSErr        MoveChild(short editType, TreeObjHndl shndl, short scnum, TreeObjHndl dhndl, short dcnum);
  177.     /* Moves a child from one location on the tree to another. */
  178.  
  179.  
  180.  
  181. OSErr        ModifyChild(short editType, TreeObjHndl phndl, short cnum, Boolean deepCopy);
  182.     /* Saves a copy of the child in the undo hierarchy for undo/redo purposes. */
  183.  
  184.  
  185.  
  186. OSErr        SwapChildren(short editType, TreeObjHndl hndla, short cnuma, TreeObjHndl hndlb, short cnumb);
  187.     /* Swaps the child handles. */
  188.  
  189.  
  190.  
  191. OSErr        SwapTreeObjData(TreeObjHndl hndla, TreeObjHndl hndlb);
  192.     /* Swaps the child data without swapping the handles. */
  193.  
  194.  
  195.  
  196. void        DisposeObjAndOffspring(TreeObjHndl childHndl);
  197.     /* This disposes of the child and any offspring of that child.  It does not remove
  198.     ** the child from the parent's child handle table. */
  199.  
  200.  
  201.  
  202. OSErr        CopyChildren(TreeObjHndl shndl, TreeObjHndl dhndl);
  203.     /* Copies the children (and children below that and so on) of one object to
  204.     ** another object.  Used internally by CopyChild for deep copies. */
  205.  
  206.  
  207.  
  208. OSErr        InsertChildHndl(TreeObjHndl parentHndl, TreeObjHndl childHndl, short childNum);
  209.     /* Adds an existing child to a parent's child handle table. */
  210.  
  211.  
  212.  
  213. void        DeleteChildHndl(TreeObjHndl parentHndl, short childNum);
  214.     /* Removes a child from the parent's child handle table. */
  215.  
  216.  
  217.  
  218. TreeObjHndl    GetRootHndl(TreeObjHndl hndl);
  219.     /* Given an object handle, return the root handle. */
  220.  
  221.  
  222.  
  223. TreeObjHndl    GetChildHndl(TreeObjHndl parentHndl, short cnum);
  224.     /* Given a parent handle and a child number, this returns the child handle. */
  225.  
  226.  
  227.  
  228. TreeObjHndl    *GetChildHndlPtr(TreeObjHndl parentHndl, short *childNum, short endCase);
  229.     /* Return a pointer into the child handle table.  This also validates (and corrects)
  230.     ** cnum so that it is in range, if possible.  Depending on the usage, pointing to
  231.     ** just after the child handle table is either valid or invalid.  If a handle is
  232.     ** being added to the table, then pointing just after the table is valid.  If a
  233.     ** handle is being removed or referenced, then pointing just after the table is
  234.     ** invalid.  the parameter endCase determines which case we are dealing with.  If
  235.     ** endCase is 0, then pointing just after the child handle table is invalid, and
  236.     ** if the cnum value passed in causes this, then nil is returned for the pointer.
  237.     ** if endCase is 1, then pointing just after the child handle table is okay, and
  238.     ** therefore nil will never be returned as the pointer.  Any cnum value out of
  239.     ** range will be corrected (if possible) to be within range. */
  240.  
  241.  
  242.  
  243. short        GetChildNum(TreeObjHndl hndl);
  244.     /* Given a child handle, this returns the child number of that
  245.     ** handle in the parent's child handle table. */
  246.  
  247.  
  248.  
  249. OSErr        AdjustDataSize(TreeObjHndl hndl, long delta);
  250.     /* Adjusts the data size, either greater or smaller, depending on the sign of 'delta'. */
  251.  
  252.  
  253.  
  254. OSErr        SetDataSize(TreeObjHndl hndl, long newSize);
  255.     /* Sets the data size to newSize. */
  256.  
  257.  
  258.  
  259. OSErr        SlideData(TreeObjHndl hndl, long offset, long delta);
  260.     /* Slides some of the data in the data portion of the object starting at
  261.     ** 'offset' by a 'delta' amount, either forward or backward, depending
  262.     ** on the sign of 'delta'. */
  263.  
  264.  
  265.  
  266. void        *GetDataPtr(TreeObjHndl hndl);
  267.     /* Returns a pointer to the beginning of the object's data area.
  268.     ** THIS DOES NOT LOCK THE HANDLE!!  The pointer may become invalid
  269.     ** if memory moves. */
  270.  
  271.  
  272.  
  273. OSErr        ReadTree(TreeObjHndl hndl, short fileRefNum);
  274.     /* Given an open file that has been previously written via WriteTree, this function
  275.     ** is called to read the file data into ram.  The root object for the file is already
  276.     ** created by InitDocument.  The file must be open, and the file position must be
  277.     ** set to the byte location where the root object of the file starts.  Once this is
  278.     ** so, just call this function with a reference to the root object and the open file
  279.     ** refrence number. */
  280.  
  281.  
  282.  
  283. OSErr        ReadTreeObjData(TreeObjHndl hndl, short fileRefNum);
  284.     /* Read in dataSize number of bytes into the object. */
  285.  
  286.  
  287.  
  288. OSErr        WriteTree(TreeObjHndl hndl, short fileRefNum);
  289.     /* Given an open file that is ready to be written to, this function is called to
  290.     ** write the file tree to the designated file. */
  291.  
  292.  
  293.  
  294. OSErr        WriteTreeObjData(TreeObjHndl hndl, short fileRefNum);
  295.     /* Write out dataSize number of bytes from the object. */
  296.  
  297.  
  298.  
  299. void        DoBTreeMethod(TreeObjHndl hndl, short message, long data);
  300.     /* Call the object for each member of the tree (or branch) starting
  301.     ** from the back of the tree working forward. */
  302.  
  303.  
  304.  
  305. OSErr        DoErrBTreeMethod(TreeObjHndl hndl, short message, long data);
  306.     /* Same as DoBTreeMethod, except that an error aborts tree walk and returns error. */
  307.  
  308.  
  309.  
  310. void        DoFTreeMethod(TreeObjHndl hndl, short message, long data);
  311.     /* Call the object for each member of the tree (or branch) starting
  312.     ** from the front of the tree working backward. */
  313.  
  314.  
  315.  
  316. OSErr        DoErrFTreeMethod(TreeObjHndl hndl, short message, long data);
  317.     /* Same as DoFTreeMethod, except that an error aborts tree walk and returns error. */
  318.  
  319.  
  320.  
  321. long        DoTreeObjMethod(TreeObjHndl hndl, short message, long data);
  322.     /* If the object has a method procedure, call it.  If no method procedure,
  323.     ** then do nothing. */
  324.  
  325.  
  326.  
  327. void        DoNumberTree(TreeObjHndl hndl);
  328.     /* Number each member in the tree with a unique treeID.  The tree is number
  329.     ** sequentially from front to back.  The first treeID number is 1.  0 is
  330.     ** reserved for Hndl2ID/ID2Hndl conversions where it is possible that the
  331.     ** handle value is nil.  The nil handle will convert to 0, and convert back
  332.     ** to nil. */
  333.  
  334.  
  335.  
  336. void        Hndl2ID(TreeObjHndl *hndl);
  337.     /* This function is used to convert a handle reference into a treeID reference.
  338.     ** A pointer to the handle reference is passed in.  Typical usage will be where
  339.     ** a handle object has a reference to another handle object.  Handle object
  340.     ** references aren't meaningful when saved to disk, and therefore don't persist
  341.     ** in their native form.  These handle references need to be converted into
  342.     ** a treeID reference so that they can be saved.
  343.     ** The tree first needs to be numbered so that the treeID references are unique
  344.     ** and meaningful.  The tree is numbered by first calling DoNumberTree().  It
  345.     ** numbers all the members of the tree hierarchy uniquely and sequentially. */
  346.  
  347.  
  348.  
  349. void        ID2Hndl(TreeObjHndl refHndl, TreeObjHndl *hndl);
  350.     /* Given a tree object ID and a reference object (any member of the tree),
  351.     ** return the cooresponding object handle.  DoNumberTree() must be called
  352.     ** prior to using this function, and after the last change to the tree, as
  353.     ** it generates the object treeID numbers for the entire tree. */
  354.  
  355.  
  356.  
  357. TreeObjHndl    GetUndoHndl(TreeObjHndl hndl);
  358.     /* Given an object handle, return the undo handle. */
  359.  
  360.  
  361.  
  362. void        NewUndo(TreeObjHndl hndl);
  363.     /* Used to close out an old undo task.  Closing out the old task means that
  364.     ** any editing to the document will be recorded into a new undo task.  Use
  365.     ** this to separate two edits of the same edit type that would otherwise
  366.     ** get recorded into the same undo task. */
  367.  
  368.  
  369.  
  370. void        RevertEdit(TreeObjHndl hndl);
  371.     /* If an edit fails, it can be backed out of by calling this.  All edits
  372.     ** that were done will be undone, thus recovering the state of the
  373.     ** document prior to the edit. */
  374.  
  375.  
  376.  
  377. void        DoUndoTask(TreeObjHndl hndl, Boolean redo, Boolean fixup);
  378.     /* Call this to undo or redo editing to the document.  If redo is false,
  379.     ** the it is an undo task.  If fixup is true, then the fixup application's
  380.     ** undo fixup procedure is called before and after the undo operation. */
  381.  
  382.  
  383.  
  384. void        DisableUndo(TreeObjHndl hndl);
  385.     /* Dispose of all undo information and prevent further undo collection.
  386.     ** Calling NewUndo() will re-enable undo collection. */
  387.  
  388.  
  389.  
  390. void        DisposeUndos(TreeObjHndl hndl);
  391.     /* Dispose of all undo information. */
  392.  
  393.  
  394.  
  395. Boolean        PurgeUndo(TreeObjHndl hndl);
  396.     /* Dispose of all undo information except the current undo.  The current undo
  397.     ** may still be active, and it may be needed to back out of an edit operation. */
  398.  
  399.  
  400.  
  401. void        GetUndoInfo(FileRecHndl frHndl, short *undoDepth, short *numUndos);
  402.     /* Return the depth of the undo state, along with the number of undos.  This
  403.     ** is useful to determine if undo and redo operations are possible.  If undoDepth
  404.     ** is non-zero, then undo is possible.  If numUndos is greater than undoDepth,
  405.     ** then redo is possible. */
  406.  
  407.  
  408.  
  409. OSErr        HReadTree(TreeObjHndl hndl, Handle tree);
  410. OSErr        HReadBranch(TreeObjHndl hndl, Handle tree);
  411. OSErr        HReadTreeObjData(TreeObjHndl hndl, Handle treeObjData);
  412. OSErr        HWriteTree(TreeObjHndl hndl, Handle tree);
  413. OSErr        HWriteTreeObjData(TreeObjHndl hndl, Handle data);
  414.     /* These functions work the same as the non-handle based versions.  Instead of
  415.     ** reading or writing to a file, these read or write to a handle.  This allows
  416.     ** you to stream the hierarchical data into a single handle that can be stored
  417.     ** as a resource or sent to another application via AppleEvents. */
  418.  
  419. long            GetCData(TreeObjHndl hndl, long offset, char *data);
  420. OSErr            PutCData(TreeObjHndl hndl, long offset, char *data);
  421. void            GetPData(TreeObjHndl hndl, long offset, StringPtr data);
  422. OSErr            PutPData(TreeObjHndl hndl, long offset, StringPtr data);
  423. OSErr            PutShortData(TreeObjHndl hndl, long offset, void *data, unsigned short size);
  424. OSErr            PutLongData(TreeObjHndl hndl, long offset, void *data, long size);
  425. unsigned long    GetDataOffset(TreeObjHndl hndl, unsigned long offset, short dtype, short dnum);
  426.  
  427. Boolean    EqualTreeObjData(TreeObjHndl h1, TreeObjHndl h2);
  428. Boolean    DefaultEqualTreeObjData(TreeObjHndl h1, TreeObjHndl h2);
  429.  
  430.  
  431.  
  432. #endif
  433.